************************************************************************* TUniKey demonstration program: UNIKEYD1.EXE This program exercises the UniKey component in a stand-alone or multi-user environment. It surfaces most of the options a programmer can control into a convenient form interface. This program can only be recompiled if you have the UNIKEY.DCU or UNIKEY.PAS files, or place the UniKey component on the form. You can try your own key table with this demo. Just create a Paradox .DB file, structuring it with one or more numeric fields. Edit this file and create one record with the starting key values in each field. For example: Customer=1001, Order=250, Item=701. Then in the demo program, each time you ask for a new key, refer to the desired field by its number: customer key is field 0, etc. Note that only the first record is used to store all keys. For a network-based test, place the key table in a directory that all workstations have read/write access to, and then run the demo program on several workstations. Use the Beep and Continuous testing options. This will let you see how often collisions occur, and let you gauge the best value for MaxRetries. *************************************************************************** TUniKey - A Delphi VCL Component for Managing Unique Keys TUniKey is a Delphi component for managing unique keys in a multi-user database environment. TUniKey manages any number of different keys such as employee id, invoice id, customer id, part number, and so forth. By default, a key value is incremented by one on each request, but the user may define an event handler to customize the key scheme, and even obtain unique alphanumeric keys. Although TUniKey is implemented using a Paradox table to store your current key values, it is completely independent of the database system, if any, that is used by the application. So keys generated by TUniKey may be stored in any other file structure or database system, but all the housekeeping, record locking, and exception control for managing the keys themselves is handled by the TUniKey component. This is an industrial strength approach to managing unique keys. TUniKey has the following features for creating robust applications that depend on the use of unique or autoincrementing keys: several "hooks" for the programmer to customize the control of key generation, automatic retries after a brief random delay after collisions with other users, alphanumeric keys, decrementing keys, "caching" numerous keys in one request for heavy traffic situations, etc. TUniKey is native Delphi VCL code that uses exception handling, event handlers, and published properties. TUniKey is a descendent class of TTable with properties that can be set at design time, or you can make a descendent that does things differently. Although fast enough for most transaction-oriented applications, TUniKey also allows for heavy-use throughput gains by permitting "more than one" key to be obtained with one call. This is done by using the Reserve property, so you can "cache" multiple key values in one call. For example, setting Reserve:=10 will give you the next new key value, and the assurance that you can just increment locally without calling UniKey to get the next nine keys - any other app (or yours) will receive the value 10-later upon its next call to TUniKey (even if the other app has Reserve still defaulting to 1). Of course, you must use the same logic locally to perform incrementing that UniKey is using, whether it is just inc(i) or something more exotic. The source code is heavily commented. For Delphi users, it is also a source of valuable information about the use of TTimers, direct BDE calls, exception handling, and the design of components. Published (Design-Time) Properties: BeepOnLock:boolean whether to beep each time table is busy or locked FieldNo:integer index of field which controls the desired key sequence MaxRetries:integer number of retries allowed before giving up - default 10 Reserve:longint number of sequential key values to reserve on this call Published (Design-Time) Events: OnMaxRetries:TUniKeyMaxHandler user-modifiable MaxRetries routine, may be a call to MessageDlg, for instance. OnNewKey:TUniKeyNewHandler user-modifiable NewKey routine, for customizing the algorithm for new keys according to your business rules. Public (Run-Time) Properties: NewKey:longint Call this for a new unique key value. OldKey:longint Can be used by user-defined key handler to see what the most recently obtained key was. Protected Methods (usable by descendent classes): function MakeNewKey:longint; virtual; procedure RaiseLockException; virtual; procedure ReleaseLock; virtual; procedure TimerEvent(Sender:TObject); virtual; function UserContinue:boolean; virtual; procedure WaitForLock; virtual; procedure XDBILock; virtual; procedure XDBIUnLock; virtual; The basic methodology of UniKey is to store the latest keys in a Paradox table. This table has only one record, but may have more than one field. Each field in the table is for a different series of keys. When the NewKey property is referenced to get a new key, the following sequence of steps occurs: 1. The master key table is opened. 2. The master key table is locked. If the lock fails because another user has the table locked, then several tries are made, controlled by a TTimer, until either a specified number of retries has elapsed or a key is successfully obtained. Upon timeout, an exception is raised. 3. The particular key of interest is read from the master key table. 4. The key is incremented (this behavior is customizable with OnNewKey). 5. The new key is put back into the record. 6. The record is posted. 7. The table is unlocked and closed. 8. The new key is returned to the application as the NewKey property value. The technique for assigning new key numbers defaults to incrementing a long integer value. This can be customized by creating an OnNewKey event handler. Create and edit a table, putting the initial key values into each field. As many fields may be used as your application(s) need different key sequences, and any numeric Paradox type may be used. Because the field number can be specified, the same incrementing scheme can be used on any number of different keys. ************************************************************************** To place an order for TUniKey, please contact Demosphere International, Inc. 2735 Hartland Road, Suite 302 Falls Church, VA 22043 Phone: 1-703-560-0400 or 1-800-949-9440 Fax: 1-703-560-0402 CompuServe: 73530,3146 Price as of April, 1995: US$29.00 Price includes full, heavily-commented source code, and a 30-day money back guarantee. ************************************ Copyright 1995, Demosphere International, Inc. License for Use: Demosphere International, Inc. (DII) grants the purchaser (User) a license to use this Component in any compiled application for any purpose (private, academic, or commercial), however User is not permitted to distribute the source code (UNIKEY.PAS) nor the object code (UNIKEY.DCU) to any other person without prior written permission of DII. UNIKEY is provided AS IS, and DII makes no claims of its fitness for any purpose, and User agrees that DII may not be held liable for any damages arising out of the use of the Component. ************************************